The new R Markdown:

Authoring dynamic scientific documents with Quarto

Marie-Hélène Burle

April 11, 2023


frontlogo

Markup & Markdown

Markup languages

Markup languages control the formatting of text documents. They are powerful but complex and the raw text (before it is rendered into its formatted version) is visually cluttered and hard to read.

Examples of markup languages include LaTeX and HTML.

Tex is used to create pdfs

Tex is often used with the macro package LaTeX.

Example LaTeX:

\documentclass{article}
\title{My title}
\author{My name}
\usepackage{datetime}
\newdate{date}{24}{11}{2022}
\date{\displaydate{date}}
\begin{document}
 \maketitle
 \section{First section}
 Some text in the first section.
\end{document}

HTML is used to create webpages

HTML is often used with css or scss files to customize the format.

Example HTML:

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>My title</title>
    <address class="author">My name</address>
    <input type="date" value="2022-11-24" />
  </head>
  <h1>First section</h1>
  <body>
    Some text in the first section.
  </body>
</html>

Markdown

A number of minimalist markup languages intend to remove all the visual clutter and complexity to create raw texts that are readable prior to rendering. Markdown (note the pun with “markup”), created in 2004, is the most popular of them. Due to its simplicity, it has become quasi-ubiquitous. Many implementations exist which add a varying number of features (as you can imagine, a very simple markup language is also fairly limited).

Markdown files are simply text files and they use the .md extension.

Basic Markdown syntax

In its basic form, Markdown is mostly used to create webpages. Conveniently, raw HTML can be included whenever the limited markdown syntax isn’t sufficient.

Here is an overview of the Markdown syntax supported by many applications.

Pandoc and its extended Markdown syntax

While the basic syntax is good enough for HTML outputs, it is very limited for other formats.

Pandoc is a free and open-source markup format converter. Pandoc supports an extended Markdown syntax with functionality for figures, tables, callout blocks, LaTeX mathematical equations, citations, and YAML metadata blocks. In short, everything needed for the creation of scientific documents.

Such documents remain as readable as basic Markdown documents (thus respecting the Markdown philosophy), but they can now be rendered in sophisticated pdf, books, entire websites, Word documents, etc.

And of course, as such documents remain text files, you can put them under version control with Git.

Pandoc and its extended Markdown syntax

Previous example using Pandoc’s Markdown:

---
title: My title
author: My name
date: 2022-11-24
---
# First section
Some text in the first section.

Literate programming

Literate programming is a methodology that combines snippets of code and written text. While first introduced in 1984, this approach to the creation of documents has truly exploded in popularity in recent years thanks to the development of new tools such as R Markdown and, later, Jupyter notebooks.

Quarto

How it works

Quarto files are turned into Markdown by Jupyter (for Python or Julia) or knitr (for R), then pandoc turns the Markdown document into the output of your choice.

Julia/Python:

noshadow From Quarto documentation

R:

noshadow From Quarto documentation

Quarto files use the extension .qmd.

You can use Quarto directly from RStudio or a Jupyter notebook.

Using Quarto directly from a Jupyter notebook:

noshadow From Quarto documentation

In this webinar, I will simply use a text editor.

Supported languages

Syntax highlighting in pretty much any language.

Executable code blocks in:

  • Python
  • R
  • Julia
  • Observable JS

Output formats

- HTML
- PDF
- MS Word
- OpenOffice
- ePub
- Revealjs
- PowerPoint
- Beamer
- GitHub Markdown
- CommonMark
- Hugo
- Docusaurus
- Markua
- MediaWiki
- DokuWiki
- ZimWiki
- Jira Wiki
- XWiki
- JATS
- Jupyter
- ConTeXt
- RTF
- reST
- AsciiDoc
- Org-Mode
- Muse
- GNU
- Groff

This training website is actually built with Quarto!

Document structure & syntax

Front matter

Written in YAML. Sets the options for the document. Let’s see a few examples.

HTML output:

---
title: "My title"
author: "My name"
format: html
---

HTML output with a few options:

---
title: "My title"
author: "My name"
format:
  html:
    toc: true
    css: <my_file>.css
---

MS Word output with Python code blocks:

---
title: "My title"
author: "My name"
format: docx
jupyter: python3
---

revealjs output with some options and Julia code blocks:

---
title: "Some title"
subtitle: "Some subtitle"
institute: "Simon Fraser University"
date: "2022-11-24"
execute:
  error: true
  echo: true
format:
  revealjs:
    theme: [default, custom.scss]
    highlight-style: monokai
    code-line-numbers: false
    embed-resources: true
jupyter: julia-1.8
---

See the Quarto documentation for an exhaustive list of options for all formats.

Written sections

Written sections are written in Pandoc’s extended Markdown.

Code blocks

If all you want is syntax highlighting of the code blocks, use this syntax:

{{.language}} <some code>

If you want syntax highlighting of the blocks and for the code to run, use instead:

```{language}
<some code>
```

In addition, options can be added to individual code blocks:

```{language}
#| <some option>: <some option value>

<some code>
```

Rendering

There are only two commands you need to know.

In a terminal, simply run either of:

quarto render <file>.qmd     # Render the document
quarto preview <file>.qmd    # Display a live preview

Examples

You can find several examples in our previous workshop on Quarto

Live demo

 Back to webinar page